library(nanoarrow)

dict_array <- as_nanoarrow_array(sample(0:9, 10, replace = TRUE))
dict_array$dictionary <- as_nanoarrow_array(stringr::words[1:10])

# default conversion is always the diciontary (value) type
infer_nanoarrow_ptype(dict_array)
#> character(0)
convert_array(dict_array)
#>  [1] "absolute" "a"        "across"   "achieve"  "accept"   "a"       
#>  [7] "active"   "a"        "a"        "across"

# this makes it type stable when consuming streams
dict1 <- as_nanoarrow_array(factor(letters[1:5]))
dict2 <- as_nanoarrow_array(factor(letters[6:10]))
stream <- basic_array_stream(list(dict1, dict2))
convert_array_stream(stream)
#>  [1] "a" "b" "c" "d" "e" "f" "g" "h" "i" "j"

# ...and more consistent when dealing with other value types
dict_array$dictionary <- as_nanoarrow_array(arrow::as_arrow_array(lapply(1:10, function(i) 1:5 * i)))
infer_nanoarrow_ptype(dict_array)
#> <list_of<integer>[0]>

# If you want a factor, you can specify it explicitly
dict_array$dictionary <- as_nanoarrow_array(stringr::words[1:10])
convert_array(dict_array, vctrs::partial_factor())
#>  [1] "absolute" "a"        "across"   "achieve"  "accept"   "a"       
#>  [7] "active"   "a"        "a"        "across"
convert_array(dict_array, factor(levels = stringr::words[10:1]))
#>  [1] absolute a        across   achieve  accept   a        active   a       
#>  [9] a        across  
#> Levels: active act across achieve account accept absolute about able a

# Also works for nesting
nested_with_dict <- as_nanoarrow_array(data.frame(x = factor(letters[1:5])))

convert_array(nested_with_dict)
#>   x
#> 1 a
#> 2 b
#> 3 c
#> 4 d
#> 5 e
convert_array(nested_with_dict, vctrs::partial_frame(x = factor()))
#>   x
#> 1 a
#> 2 b
#> 3 c
#> 4 d
#> 5 e

library(nanoarrow)

num_levels <- 1e1
vec_len <- 1e6

vec <- nanoarrow:::vec_gen(character(), n = num_levels)
vec_chr <- do.call(c, rep(list(vec), vec_len / num_levels))
vec_chr <- nanoarrow:::vec_shuffle(vec_chr)
vec_fct <- factor(vec_chr)
levels <- levels(vec_fct)

array_chr <- as_nanoarrow_array(vec_chr)
array_fct <- as_nanoarrow_array(vec_fct)

arrow_chr <- arrow::as_arrow_array(array_chr)
arrow_fct <- arrow::as_arrow_array(array_fct)

bench::mark(
  convert_array(array_chr),
  as.vector(arrow_chr)
)
#> # A tibble: 2 × 6
#>   expression                    min   median `itr/sec` mem_alloc `gc/sec`
#>   <bch:expr>               <bch:tm> <bch:tm>     <dbl> <bch:byt>    <dbl>
#> 1 convert_array(array_chr)    2.3µs   2.71µs   328706.   23.95KB     65.8
#> 2 as.vector(arrow_chr)       4.26µs    4.8µs   191042.    7.87KB     38.2

bench::mark(
  convert_array(array_fct),
  convert_array(array_fct, factor()),
  convert_array(array_fct, factor(levels = levels)),
  as.vector(arrow_fct$cast(arrow::string())),
  as.vector(arrow_fct),
  check = FALSE
)
#> # A tibble: 5 × 6
#>   expression                                             min   median `itr/sec`
#>   <bch:expr>                                        <bch:tm> <bch:tm>     <dbl>
#> 1 convert_array(array_fct)                           40.55ms  41.06ms      24.4
#> 2 convert_array(array_fct, factor())                  2.97ms   3.18ms     306. 
#> 3 convert_array(array_fct, factor(levels = levels))   2.83ms   3.15ms     314. 
#> 4 as.vector(arrow_fct$cast(arrow::string()))         48.35ms  49.18ms      20.2
#> 5 as.vector(arrow_fct)                                6.19µs   7.22µs  110825. 
#> # ℹ 2 more variables: mem_alloc <bch:byt>, `gc/sec` <dbl>

# Mitigate ALTREP
bench::mark(
  convert_array(array_fct)[1e6:1],
  convert_array(array_fct, factor())[1e6:1],
  convert_array(array_fct, factor(levels = levels))[1e6:1],
  as.vector(arrow_fct$cast(arrow::string()))[1e6:1],
  as.vector(arrow_fct)[1e6:1],
  check = FALSE
)
#> # A tibble: 5 × 6
#>   expression                                                      min   median
#>   <bch:expr>                                                 <bch:tm> <bch:tm>
#> 1 convert_array(array_fct)[1e+06:1]                           45.87ms  45.87ms
#> 2 convert_array(array_fct, factor())[1e+06:1]                  5.42ms   5.78ms
#> 3 convert_array(array_fct, factor(levels = levels))[1e+06:1]   5.39ms   5.79ms
#> 4 as.vector(arrow_fct$cast(arrow::string()))[1e+06:1]         92.85ms  94.93ms
#> 5 as.vector(arrow_fct)[1e+06:1]                               15.42ms  15.76ms
#> # ℹ 3 more variables: `itr/sec` <dbl>, mem_alloc <bch:byt>, `gc/sec` <dbl>